---
type: integration
title: '@astrojs/mdx'
description: Astro 프로젝트에서 @astrojs/mdx 통합을 사용하는 방법을 알아보세요.
sidebar:
  label: MDX
githubIntegrationURL: 'https://github.com/withastro/astro/tree/main/packages/integrations/mdx/'
category: other
i18nReady: true
---
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'
import ReadMore from '~/components/ReadMore.astro'
import Since from '~/components/Since.astro'

이 **[Astro 통합][astro-integration]을** 통해 [MDX](https://mdxjs.com/) 컴포넌트를 사용할 수 있으며 페이지를 `.mdx` 파일로 생성할 수 있습니다.

## 왜 MDX인가?

MDX를 사용하면 Astro에서 Markdown 콘텐츠 내에서 변수, JSX 표현식 및 컴포넌트를 사용할 수 있습니다. MDX로 작성된 기존 콘텐츠가 있는 경우 이 통합을 통해 해당 파일을 Astro 프로젝트로 가져올 수 있습니다.

## 설치

Astro에는 공식 통합 설정을 자동화하는 `astro add` 명령이 포함되어 있습니다. 원하는 경우 대신 [통합을 수동으로 설치](#수동-설치)할 수 있습니다.

새 터미널 창에서 다음 명령 중 하나를 실행합니다.

<PackageManagerTabs>
  <Fragment slot="npm">
  ```sh
  npx astro add mdx
    ```
  </Fragment>
  <Fragment slot="pnpm">
  ```sh
  pnpm astro add mdx
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```sh
  yarn astro add mdx
  ```
  </Fragment>
 </PackageManagerTabs>

문제가 발생하면 [GitHub에서 언제든지 보고](https://github.com/withastro/astro/issues)하고 아래 수동 설치 단계를 시도해 보세요.

### 수동 설치

먼저 `@astrojs/mdx` 패키지를 설치하세요.

<PackageManagerTabs>
  <Fragment slot="npm">
  ```sh
  npm install @astrojs/mdx
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```sh
  pnpm add @astrojs/mdx
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```sh
  yarn add @astrojs/mdx
  ```
  </Fragment>
</PackageManagerTabs>

그런 다음 `integrations` 속성을 사용하여 `astro.config.*` 파일에 통합을 적용합니다.

```js title="astro.config.mjs" ins={2} ins="mdx()"
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  // ...
  integrations: [mdx()],
});
```

### 편집기 통합

[VS Code](https://code.visualstudio.com/)에서 편집기를 지원하려면 [공식 MDX 확장 프로그램](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx)을 설치하세요.

다른 편집기의 경우 [MDX 언어 서버](https://github.com/mdx-js/mdx-analyzer/tree/main/packages/language-server)를 사용하세요.

## 사용하기

표준 MDX 기능 사용에 대해 알아보려면 [MDX 문서](https://mdxjs.com/docs/what-is-mdx/)를 참조하세요.

## Astro에서 MDX 사용하기

MDX 통합을 추가하면 JSX 변수, 표현식, 컴포넌트로 Markdown을 작성하는 기능이 향상됩니다.

또한 MDX에서 Markdown 스타일의 프런트매터를 지원하는 등 표준 MDX에 기능이 추가됩니다. 이를 통해 대부분의 [Astro에 내장된 Markdown 기능](/ko/guides/markdown-content/)을 사용할 수 있습니다.

`.mdx` 파일은 Astro의 HTML과 유사한 구문이 아닌 [MDX 구문](https://mdxjs.com/docs/what-is-mdx/#mdx-syntax)으로 작성해야 합니다.

### MDX와 콘텐츠 컬렉션 함께 사용하기

콘텐츠 컬렉션에 MDX 파일을 포함하려면, [컬렉션 로더](/ko/guides/content-collections/#컬렉션-loader-정의)가 `.mdx` 파일의 콘텐츠를 로드하도록 구성되어 있는지 확인하세요:

```js title="src/content.config.ts" ins="mdx"
import { defineCollection, z } from 'astro:content';
import { glob } from 'astro/loaders';

const blog = defineCollection({
  loader: glob({ pattern: "**/*.{md,mdx}", base: "./src/blog" }),
  schema: z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z.coerce.date(),
  })
});

export const collections = { blog };
```

### 내보낸 변수를 MDX에서 사용하기

MDX는 `export` 문을 사용하여 MDX 콘텐츠에 변수를 추가하거나 이를 가져오는 컴포넌트로 데이터를 내보내는 기능을 지원합니다.

예를 들어, MDX 페이지 또는 컴포넌트에서 `{JSX 표현식}`을 제목으로 사용할 `title` 필드를 내보낼 수 있습니다:

```mdx title="/src/blog/posts/post-1.mdx"
export const title = 'My first MDX post'

# {title}
```

또는 `import` 및 `import.meta.glob()` 문을 사용하여, 내보낸 `title`을 페이지에서 사용할 수 있습니다:

```astro title="src/pages/index.astro"
---
const matches = import.meta.glob('./posts/*.mdx', { eager: true });
const posts = Object.values(matches);
---

{posts.map(post => <p>{post.title}</p>)}
```

#### 내보낸 속성

`import` 문 또는 `import.meta.glob()`을 사용할 때, `.astro` 컴포넌트에서 사용할 수 있는 속성은 다음과 같습니다:

- **`file`** - 파일의 절대 경로 (예: `/home/user/projects/.../file.mdx`).
- **`url`** - 페이지의 URL (예: `/en/guides/markdown-content`).
- **`frontmatter`** - 파일의 YAML/TOML 프런트매터에 지정된 모든 데이터를 포함합니다.
- **`getHeadings()`** - 파일에 있는 모든 제목 (`<h1>`에서 `<h6>`)의 배열 (타입은 `{ depth: number; slug: string; text: string }[]`)을 반환하는 비동기 함수입니다. 각 제목의 `slug`는 주어진 제목에 대해 생성된 ID에 해당하며 링크로 사용될 수 있습니다.
- **`<Content />`** - 파일의 렌더링된 전체 콘텐츠를 반환하는 컴포넌트입니다.
- **(모든 `export` 값)** - MDX 파일은 `export` 문을 사용하여 데이터를 내보낼 수도 있습니다.

### MDX에서 프런트매터 변수 사용하기

기본적으로 Astro MDX 통합은 MDX에서 프런트매터를 사용하는 것을 지원합니다. Markdown 파일과 마찬가지로 프런트매터 속성을 추가하면 이러한 변수를 템플릿에서 사용할 수 있으며, 다른 곳에서 파일을 가져올 때 명명된 속성으로도 사용할 수 있습니다.

```mdx title="/src/blog/posts/post-1.mdx"
---
title: 'My first MDX post'
author: 'Houston'
---

# {frontmatter.title}

Written by: {frontmatter.author}
```

### MDX에서 컴포넌트 사용하기

MDX 통합을 설치한 후에는 다른 Astro 컴포넌트에서 사용하는 것과 마찬가지로 MDX (`.mdx`) 파일에서 [Astro 컴포넌트](/ko/basics/astro-components/)와 [UI 프레임워크 컴포넌트](/ko/guides/framework-components/#프레임워크-컴포넌트-사용) 모두를 가져와서 사용할 수 있습니다.

필요한 경우 UI 프레임워크 컴포넌트에 `client:지시어`를 포함시키는 것을 잊지 마세요!

가져오기 및 내보내기 문 사용에 대한 자세한 예는 [MDX 문서](https://mdxjs.com/docs/what-is-mdx/#esm)를 참조하세요.

```mdx title="src/blog/post-1.mdx" {4,9}
---
title: My first post
---
import ReactCounter from '../components/ReactCounter.jsx';

I just started my new Astro blog!

Here is my counter component, working in MDX:
<ReactCounter client:load />
```

#### HTML 요소에 사용자 정의 컴포넌트 할당하기

MDX를 사용하면 표준 HTML 요소 대신 Markdown 구문을 사용자 정의 컴포넌트에 매핑할 수 있습니다. 이렇게 하면 표준 Markdown 구문으로 작성하되 선택한 요소에 특별한 컴포넌트 스타일을 적용할 수 있습니다.

예를 들어, `<blockquote>` 콘텐츠에 사용자 정의 스타일을 제공하는 `Blockquote.astro` 컴포넌트를 만들 수 있습니다.

```astro title="src/components/Blockquote.astro"
---
const props = Astro.props;
---
<blockquote {...props} class="bg-blue-50 p-4">
  <span class="text-4xl text-blue-600 mb-2">“</span>
  <slot /> <!-- 하위 콘텐츠를 위해 `<slot/>`을 추가해야 합니다! -->
</blockquote>
```

사용자 정의 컴포넌트를 `.mdx` 파일로 가져온 다음 표준 HTML 요소를 사용자 정의 컴포넌트에 매핑하는 `components` 객체를 내보냅니다.

```mdx title="src/blog/posts/post-1.mdx"
import Blockquote from '../components/Blockquote.astro';
export const components = {blockquote: Blockquote}

> This quote will be a custom Blockquote
```

사용자 정의 컴포넌트로 덮어쓸 수 있는 HTML 요소의 전체 목록은 [MDX 웹사이트](https://mdxjs.com/table-of-components/)를 참조하세요.

:::note
MDX 파일에서 정의되어 내보내진 사용자 정의 컴포넌트는 가져온 다음 `components` 속성을 통해 `<Content />` 컴포넌트로 다시 전달되어야 합니다.
:::

#### `components`를 MDX 콘텐츠로 전달하기

가져온 MDX 콘텐츠를 `<Content />` 컴포넌트를 사용하여 렌더링할 때 (콘텐츠 컬렉션을 사용한 MDX 항목 렌더링 포함), `components` prop을 통해 사용자 정의 컴포넌트를 전달할 수 있습니다. 이러한 컴포넌트는 `<Content />` 컴포넌트에서 사용할 수 있도록 먼저 가져와야 합니다.

`components` 객체는 HTML 요소 이름(`h1`, `h2`, `blockquote` 등)을 사용자 정의 컴포넌트에 매핑합니다. 또한 스프레드 연산자(`...`)를 사용하여 [MDX 파일 자체에서 내보낸 모든 컴포넌트](#html-요소에-사용자-정의-컴포넌트-할당하기)를 포함할 수 있으며, 이 또한 MDX 파일에서 `components`로 가져와야 합니다.

Astro 컴포넌트에서 사용하기 위해 단일 파일에서 MDX를 직접 가져오는 경우, `Content` 컴포넌트와 MDX 파일에서 내보낸 모든 컴포넌트를 모두 가져와야 합니다.

```astro title="src/pages/page.astro" "components={{...components, h1: Heading }}" {2}
---
import { Content, components } from '../content.mdx';
import Heading from '../Heading.astro';
---
<!-- '#' 구문에서 사용할 사용자 정의 <h1>을 생성하고, `content.mdx`에 정의된 사용자 정의 컴포넌트를 적용합니다. -->
<Content components={{...components, h1: Heading }} />
```

MDX 파일이 콘텐츠 컬렉션 항목인 경우, `astro:content`의 `render()` 함수를 사용하여 `<Content />` 컴포넌트에 접근하세요.

다음은 `<h1>` HTML 요소 대신 사용될 사용자 정의 제목을 `components` prop을 통해 `<Content />` 컴포넌트에 전달하는 예시입니다.

```astro title="src/pages/blog/post-1.astro" ins="components={{ h1: CustomHeading }}"
---
import { getEntry, render } from 'astro:content';
import CustomHeading from '../../components/CustomHeading.astro';
const entry = await getEntry('blog', 'post-1');
const { Content } = await render(entry);
---
<Content components={{ h1: CustomHeading }} />
```

## 구성

MDX 통합이 설치되면 Astro 프로젝트에서 `.mdx` 파일을 사용하기 위해 구성할 필요가 없습니다.

다음 옵션을 사용하여 MDX가 렌더링되는 방식을 구성할 수 있습니다.

* [Markdown 구성에서 상속된 옵션](#markdown-구성에서-상속된-옵션)
* [`extendMarkdownConfig`](#extendmarkdownconfig)
* [`recmaPlugins`](#recmaplugins)
* [`optimize`](#optimize)

### Markdown 구성에서 상속된 옵션

모든 [`markdown` 구성 옵션](/ko/reference/configuration-reference/#markdown-옵션)은 MDX 통합에서 별도로 구성할 수 있습니다. 여기에는 remark 및 rehype 플러그인, 구문 강조 등이 포함됩니다. 옵션은 기본적으로 Markdown 구성의 옵션으로 설정됩니다 ([이를 수정하려면 `extendMarkdownConfig` 옵션 참조](#extendmarkdownconfig)).

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
import remarkToc from 'remark-toc';
import rehypePresetMinify from 'rehype-preset-minify';

export default defineConfig({
  // ...
  integrations: [
    mdx({
      syntaxHighlight: 'shiki',
      shikiConfig: { theme: 'dracula' },
      remarkPlugins: [remarkToc],
      rehypePlugins: [rehypePresetMinify],
      remarkRehype: { footnoteLabel: 'Footnotes' },
      gfm: false,
    }),
  ],
});
```

:::caution
MDX는 remark 및 rehype 플러그인을 문자열로 전달하는 것을 지원하지 않습니다. 대신 플러그인 기능을 설치하고 가져와 적용해야 합니다.
:::

<ReadMore>전체 옵션 목록은 [Markdown 옵션 참조](/ko/reference/configuration-reference/#markdown-옵션)를 확인하세요.</ReadMore>

### `extendMarkdownConfig`

<p>

**타입:** `boolean`<br />
**기본값:** `true`<br />
<Since v="0.15.0" pkg="@astrojs/mdx" />
</p>

MDX는 기본적으로 [프로젝트의 기존 Markdown 구성](/ko/reference/configuration-reference/#markdown-옵션)을 확장합니다. 개별 옵션을 재정의하려면 MDX 구성에서 해당 옵션을 지정하면 됩니다.

예를 들어 GitHub 기반 Markdown을 비활성화하고 MDX 파일에 대해 다른 remark 플러그인 세트를 적용해야 한다고 가정해 보겠습니다. 기본적으로 `extendMarkdownConfig`가 활성화된 상태에서 이러한 옵션을 다음과 같이 적용할 수 있습니다.

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  // ...
  markdown: {
    syntaxHighlight: 'prism',
    remarkPlugins: [remarkPlugin1],
    gfm: true,
  },
  integrations: [
    mdx({
      // Markdown에서 상속된 `syntaxHighlight`

      // 마크다운 `remarkPlugins`가 무시되었습니다.
      // `remarkPlugin2`만 적용되었습니다.
      remarkPlugins: [remarkPlugin2],
      // `gfm`이 `false`로 재정의되었습니다.
      gfm: false,
    }),
  ],
});
```

MDX에서 `markdown` 구성 확장을 비활성화해야 할 수도 있습니다. 이를 위해 `extendMarkdownConfig`를 `false`로 설정하세요.

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  // ...
  markdown: {
    remarkPlugins: [remarkPlugin1],
  },
  integrations: [
    mdx({
      // markdown 구성은 이제 무시됩니다.
      extendMarkdownConfig: false,
      // 'remarkPlugins'가 적용되지 않았습니다.
    }),
  ],
});
```

### `recmaPlugins`

<p>

**타입:** `PluggableList`<br />
**기본값:** `[]`<br />
<Since v="0.11.5" pkg="@astrojs/mdx" />
</p>

출력되는 [estree](https://github.com/estree/estree)를 직접 수정하는 플러그인입니다. 이는 MDX 파일에서 JavaScript 변수를 수정하거나 삽입하는 데 유용합니다.

[AST Explorer를 사용](https://astexplorer.net/)하여 estree 출력을 수행하고 [`estree-util-visit`](https://unifiedjs.com/explore/package/estree-util-visit/)를 사용하여 JavaScript 노드를 검색하는 것이 좋습니다.

### `optimize`

<p>

**타입:** `boolean | { ignoreElementNames?: string[] }`<br />
**기본값:** `false`<br />
<Since v="0.19.5" pkg="@astrojs/mdx" />
</p>

이는 내부 rehype 플러그인을 통해 더 빠른 빌드 및 렌더링을 위해 MDX 출력을 최적화하기 위한 선택적 구성 설정입니다. MDX 파일이 많고 빌드 속도가 느린 경우에 유용할 수 있습니다. 그러나 이 옵션은 일부 이스케이프 처리되지 않은 HTML을 생성할 수 있으므로 활성화한 후에도 사이트의 대화형 부분이 여전히 올바르게 작동하는지 확인하세요.

이는 기본적으로 비활성화되어 있습니다. MDX 최적화를 활성화하려면 MDX 통합 구성에 다음을 추가하십시오.

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  // ...
  integrations: [
    mdx({
      optimize: true,
    }),
  ],
});
```

#### `ignoreElementNames`

<p>

**타입:** `string[]`<br />
<Since v="3.0.0" pkg="@astrojs/mdx" />
</p>

이전에는 `customComponentNames`로 알려졌습니다.

MDX 최적화 프로그램이 [컴포넌트 prop을 통해 가져온 MDX 콘텐츠에 전달된 사용자 정의 컴포넌트](#components를-mdx-콘텐츠로-전달하기)와 같은 특정 요소 이름을 처리하지 못하도록 방지하는 `optimize`의 선택적 속성입니다.

최적화 프로그램이 콘텐츠를 정적 문자열로 변환하므로 동적으로 렌더링해야 하는 사용자 정의 컴포넌트가 중단되기 때문에 최적화에서 이러한 컴포넌트를 제외해야 합니다.

예를 들어 다음 의도된 MDX 출력은 모두 `"<h1>...</h1>"`이 아닌 `<Heading>...</Heading>`입니다.

```astro
---
import { Content, components } from '../content.mdx';
import Heading from '../Heading.astro';
---

<Content components={{ ...components, h1: Heading }} />
```

`ignoreElementNames` 속성을 사용하여 이에 대한 최적화를 구성하려면 맞춤 컴포넌트로 처리되어야 하는 HTML 요소 이름의 배열을 지정하세요.

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  // ...
  integrations: [
    mdx({
      optimize: {
        // 최적화 프로그램이 'h1' 요소를 처리하지 못하도록 방지
        ignoreElementNames: ['h1'],
      },
    }),
  ],
});
```

MDX 파일이 [`export const components = { ... }`를 사용하여 사용자 정의 컴포넌트를 구성](/ko/guides/integrations-guide/mdx/#html-요소에-사용자-정의-컴포넌트-할당하기)하는 경우, 이 옵션을 수동으로 구성할 필요가 없습니다. 최적화 프로그램은 이를 자동으로 감지합니다.

## 예시

[Astro MDX 시작 템플릿](https://github.com/withastro/astro/tree/latest/examples/with-mdx)은 Astro 프로젝트에서 MDX 파일을 사용하는 방법을 보여줍니다.

[astro-integration]: /ko/guides/integrations-guide/

[astro-ui-frameworks]: /ko/guides/framework-components/#using-framework-components
